Night Owl 6/Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso/038a/qbrv1_2.zip/BASUTL.DOC

Text File | 1991-11-22 | 18KB | 655 lines

          ============================================================

                             B A S I C   S O U R C E

            M E R G E,  C O M P A R E  &  F I N D   U T I L I T I E S

                            U S E R ' S   M A N U A L

                               by Richard Z. Ward

                                   Version 1.1

                             PC/MS-DOS 2.0 or Later


          (C) Copyright 1986-1991 Richard Z. Ward, All Rights Reserved

          ============================================================








     L I C E N S E   A G R E E M E N T ------------------------------


     --------- A Limited License

     A limited license is granted to all users of the programs to make
     copies of the programs and the accompanying documentation and to
     distribute them to other users under the following restrictions:

     1. Neither a fee nor any other consideration may be charged for
     copying or distributing the programs without the express written
     permission from Richard Z. Ward.

     2. The programs and their documentation may not be distributed in
     modified forms.


     --------- Shareware Registration

     The BASIC Utility programs are the result of many hours of work.  If
     you find them useful, please register your copies of the programs.  To
     register, fill out a hard copy of the ORDERFRM.DOC file, write a check
     for $7.50 to Richard Z. Ward, and send the form and check to the
     following address:

          Richard Z. Ward / WARDCO
          P.O. Box 454
          Belmont, MA 02178

     You will then receive a newly serialized copy of the program and a
     complete set of printed instructions.  As a registered user, you will
     be notified of all future updates to the program; the first update
     from the version you registered will be sent to you at no charge.


     --------- User Support and Defects and Enhancements

     If you have any suggestions for future versions of the BASIC Utility
     programs or find any defects in the existing versions, please fill out
     a hard copy of the DEFECTS.DOC file and send the form to the above
     address.

     Otherwise, If you are having trouble using the programs, please send
     your written questions to the above address.








     BASMER, BASCMP & BASFND Utilities User's Manual            Page 2








     --------- Warranty/Liability

     Should a BASIC Utility programs' disk fail due to defects in materials
     or workmanship, it will be replaced at no charge.  No other
     representations or warranties are made, express or implied.

     In no event shall Richard Z. Ward be liable for any direct, indirect,
     consequential or incidental damages arising from the use of the BASIC
     Utility programs.











































     BASMER, BASCMP & BASFND Utilities User's Manual            Page 3








     The Basic Source Merge Utility ----------------------------


     --------- Introduction

     The Basic Source Merge utility has been designed to merge and sort any
     two MicroSoft BASIC or GWBASIC source files.  If you write many BASIC
     programs (or one large BASIC program), BASMER will increase your
     productivity: BASMER has many useful and time-saving applications.

     For instance, if you have several versions of a program, you may find
     it useful to separate the sections that distinguish each version from
     the main program and save them in modules.  In this way, you can merge
     a module
     with the main program in order to create a new version suited for a
     specific application or computer.

     Moreover, once you have created these modules from the main program,
     you will find it easier and less time-consuming to modify the one main
     program, rather than the several slightly different versions of your
     program.
     In short, updating a series of programs would become an easier and
     less confusing task.


     --------- On-line Instructions

     To read the short on-line instructions to the utility, from the Disk
     Operating System, type BASMER.  BASMER will display a brief
     description of its functions and a summary of its command parameters.


     --------- Getting Started

     To merge two BASIC source files, type:

          BASMER Primary Secondary [/O][/P] ,

     where Primary and Secondary refer to two distinct BASIC source files
     saved in ASCII format.












     BASMER, BASCMP & BASFND Utilities User's Manual            Page 4








     --------- Primary and Secondary Files

     Before starting BASMER, however, you must decide which of the two
     source files is the primary file.  BASMER will create a new primary
     file with a .MRG extension, and write the output of the merge
     operation to this file.

     For example, the command

          BASMER TEST SECOND

     instructs BASMER to treat the file TEST.BAS as the primary file, and
     SECOND.BAS as the secondary file.  BASMER will create TEST.MRG, and
     will write the union of TEST.BAS and SECOND.BAS to the new TEST.MRG
     file.


     --------- File Extensions

     BASMER recognizes three file extensions: BAS, BAK and MOD.  When no
     file extension is specified on the command line, BASMER assumes the
     BAS extension (note the above example).

     The MOD file extension refers to a module or subprogram of any main
     BASIC source file.  This file extension makes it easier to distinguish
     modules from main source files.


     --------- Over-write Parameter /O

     The over-write parameter instructs BASMER to write over information
     found in identically numbered lines in the primary file.  If the /O
     parameter is omitted, BASMER will add and comment identically numbered
     lines from the
     secondary to the primary file.  If the lines themselves are identical,
     however, BASMER will write only single copies of the lines to the new
     primary file.

     For example, let line 10 of the example primary file TEST.BAS read 10
     PRINT "PROGRAM TEST", and let line 10 of the example secondary file
     SECOND.BAS read 10 GOTO 100.  The over-write parameter (/O) will
     instruct BASMER to
     replace line 10 of TEST.BAS with that of SECOND.BAS.

     Otherwise, BASMER will write line 10 from TEST.BAS to the new TEST.BAS
     file and follow it with a commented line 10 from SECOND.BAS.  A
     commented line of code contains an (') apostrophe and a tab character
     as its first two characters.  Note that the MicroSoft BASICA
     interpreter does not support
     the apostrophe (') comment character.


     BASMER, BASCMP & BASFND Utilities User's Manual            Page 5







     --------- Print Parameter /P

     The print parameter instructs BASMER to send output messages to the
     printer as well as to the monitor.  The output messages include a
     Copyright notice, a list of identically numbered but not duplicate
     lines, the total number of such lines, the total number of new lines
     sorted and inserted in the primary file, and the number of non-indexed
     lines.

     If the printer is off-line or disconnected, BASMER will continue
     execution and display the output messages on your video monitor.
     BASMER will not display any error messages concerning the status of
     the printer.


     --------- Non-indexed Lines

     BASMER writes to the new file line by line, sorting, and adding lines
     taken from both source files.  Because it sorts by line numbers,
     BASMER may not run reliably if it encounters a file with only a few
     numbered lines.

     BASMER will not discontinue operation upon finding an unnumbered line,
     however.  Instead, it will keep track of the number of non-indexed
     lines, and inform you at the end of its execution.

     Please note that BASMER has no trouble with an occasional non-indexed
     line.  But, more than one in a row will present problems.


     --------- Reserved Characters

     There are a few reserved characters that BASMER assumes do not exist
     in your source files.  These characters have ASCII values of zero (0)
     and twenty-seven (27).  Since most editors will not allow you to enter
     such values, this should not pose any problem.  However, if your
     program has these characters in its source file, BASMER will not run
     reliably.

     If you are not sure if your source has these characters, it probably
     does not.  It takes some extra effort to insert them in source code.
     For example, the non-document mode of WordStar will uses these control
     characters for standard word processing operations.










     BASMER, BASCMP & BASFND Utilities User's Manual            Page 6








     --------- System Requirements

     The following configuration is the minimum which is required to gain
     access to all of the features of BASMER.

          * IBM PC family member or Compatible w/128K
          * One disk drive
          * A monochrome or color display
          * A printer
          * PC/MS-DOS version 2.0 or later


     --------- IBM Compatible Personal Computers

     BASMER.COM was written, assembled and tested on an IBM PC. Since it
     relies on very few IBM interrupt routines, BASMER should work well on
     any IBM compatible personal computer.



































     BASMER, BASCMP & BASFND Utilities User's Manual            Page 7







     The Basic Source Compare Utility --------------------------


     --------- Introduction

     BASCMP displays or prints the differences between two BASIC source
     files.  It marks the differences by line number, rather than by
     hexadecimal address.  Thus, the output is both readable and
     understandable.

     If you write many BASIC programs or are currently working on a large
     BASIC program, BASCMP will be an invaluable aid: BASCMP has many
     useful and time-saving applications.

     For example, if you write programs and support a software package
     written in BASIC, you may find it useful to save the source code of
     each version supported in the market.  BASCMP will quickly display
     differences between the individual versions.  Thus, you can quickly
     and reliably update any version of your program: have BASCMP compare
     the newest version to the one you want to update.


     --------- On-line Instructions

     To read the short on-line instructions, from the Disk Operating
     System, type BASCMP.  BASCMP will display a short description of its
     functions and a summary of its command parameters.


     --------- Getting Started

     To compare two BASIC source files, type:

          BASCMP path1 path2 [/P]

     where path1 and path2 refer to two distinct BASIC source files. Note
     that the order of files in the command line is not critical: it only
     affects the BASCMP display.

     --------- File Extensions

     BASCMP recognizes three file extensions: BAS, BAK and MOD. When no
     file extension is specified on the command line, BASCMP assumes the
     BAS extension.









     BASMER, BASCMP & BASFND Utilities User's Manual            Page 8








     --------- Print Parameter /P

     The Print parameter instructs BASCMP to send the output messages to
     the printer.  Providing hard-copies of the differences between two
     BASIC source files is an invaluable function for programmers.

     The BASCMP messages include a Copyright notice, a list of the lines
     that differ from file to file, the total number of different lines,
     and the number of non-indexed lines found.

     If the printer is not ready to accept characters, BASCMP will continue
     execution and display the output messages on the video monitor.
     BASCMP will not display any error messages concerning the status of
     the printer.


     -------- Non-indexed Lines

     Because it compares the two BASIC source files by line numbers, BASCMP
     will not run reliably if it encounters a file with only a few numbered
     lines.

     Like BASMER, BASCMP will not discontinue operation upon finding an
     unnumbered line.  Instead, it will count the number of non-indexed
     lines, and display a warning message at the end of its execution.

     BASCMP has no trouble with an occasional non-indexed line.  But, more
     than one in a row may cause BASCMP to lose track of which lines it is
     supposed to compare.


     --------- Reserved Characters

     BASCMP assumes that ASCII values of zero (0) and twenty-seven (27) are
     not in your source files.  If your program has these characters in its
     source file, BASCMP will will not run reliably.

     BASCMP uses ASCII character zero and twenty-seven to keep track of the
     small section of a file that is loaded in memory.  Both BASMER and
     BASCMP only load five kilobytes of any one file at a time.


     --------- System Requirements (See same section for BASMER)









     BASMER, BASCMP & BASFND Utilities User's Manual            Page 9








     The Basic Source Find Utility -----------------------------


     --------- Introduction

     The Basic Source Find utility has been designed to find almost any set
     of ASCII characters in any BASIC source file.  BASFND will display all
     lines in which the string of ASCII characters is found.  If you write
     many BASIC programs (or one large BASIC program), BASFND will
     immediately increase
     your productivity: BASFND has many useful and time-saving
     applications.

     First, since many of the most popular programming editors will not
     "search" for control characters in a file, you will find it useful to
     have BASFND search for these characters.  Then, you can use your
     programming editor to make the actual changes in the source file.

     Second, by listing lines of BASIC code according to a certain variable
     or set of characters, BASFND allows you to edit a BASIC source file
     with a clearer understanding of the tasks involved.  In this way,
     BASFND helps to keep your time spent editing a BASIC program
     productive.

     Finally, regardless of the programming editor, it is easy to get lost
     in a long BASIC source file -- especially if you are not familiar with
     the code.  By grouping and listing distant lines of code, BASFND helps
     to remedy this problem.


     --------- On-line Instructions

     To read the short on-line instructions to the utility, from the Disk
     Operating System, type BASFND.  BASFND will display a brief
     description of its functions and a summary of its command parameters.


     --------- Getting Started

     To find ASCII characters in a BASIC source file, type:

          BASFND [Pathname] [/P] ,

     where Pathname refers to the BASIC source file saved in ASCII
     format on a specified directory.







     BASMER, BASCMP & BASFND Utilities User's Manual            Page 10








     --------- File Extensions

     BASFND recognizes three file extensions: BAS, BAK and MOD.  When no
     file extension is specified on the command line, BASFND assumes the
     BAS extension.

     The MOD file extension refers to a module or subprogram of any main
     BASIC source file.  This file extension makes it easier to distinguish
     modules from main source files.


     --------- Print Parameter /P

     The print parameter instructs BASFND to send output messages to the
     printer as well as to the monitor.  The output messages include a
     Copyright notice, a list of lines that contain the specified set of
     ASCII characters,
     and the total number of lines found.

     If the printer is off-line or disconnected, BASFND will continue
     execution and display the output messages on your video monitor.
     BASFND will not display any error messages concerning the status of
     the printer.


     --------- Reserved Characters

     There are a few reserved characters that BASFND assumes do not exist
     in your source files.  These characters have ASCII values of zero (0)
     and twenty-seven (27).  Since most editors will not allow you to enter
     such values, this should not pose any problem.  However, if your
     program has these characters in its source file, BASFND will not run
     reliably.

     Furthermore, note that BASFND will not search for a character having
     an ASCII value of twenty-six (26).  If you press the ESC key, BASFND
     will abort execution and return you to DOS.


     --------- System Requirements (See same section for BASMER)












     BASMER, BASCMP & BASFND Utilities User's Manual            Page 11